Common Caddyfile Patterns

This page demonstrates a few complete and minimal Caddyfile configurations for common use cases. These can be helpful starting points for your own Caddyfile documents.

These are not drop-in solutions; you will have to customize your domain name, ports/sockets, directory paths, etc. They are intended to illustrate some of the most common configuration patterns.

As usual, the first line is the site address. The root directive specifies the path to the root of the site (the * means to match all requests, so as to disambiguate from a path matcher)鈥攃hange the path to your site if it isn't the current working directory. Finally, we enable the static file server.

Proxy all requests:

Only proxy requests having a path starting with /api/ and serve static files for everything else:

With a PHP FastCGI service running, something like this works for most modern PHP apps:

Customize the site root accordingly; this example assumes that your PHP app's webroot is within a public directory鈥攔equests for files that exist on disk will be served with file_server, and anything else will be routed to index.php for handling by the PHP app.

The php_fastcgi directive is actually just a shortcut for several pieces of configuration.

To add the www. subdomain with an HTTP redirect:

To remove it:

To remove it for multiple domains at once; this uses the {labels.*} placeholders which are the parts of the hostname, 0-indexed from the right (e.g. 0=com, 1=example-one, 2=www):

You will not usually need to configure this yourself; the file_server directive will automatically add or remove trailing slashes from requests by way of HTTP redirects, depending on whether the requested resource is a directory or file, respectively.

However, if you need to, you can still enforce trailing slashes with your config. There are two ways to do it: internally or externally.

This uses the rewrite directive. Caddy will rewrite the URI internally to add or remove the trailing slash:

Using a rewrite, requests with and without the trailing slash will be the same.

This uses the redir directive. Caddy will ask the browser to change the URI to add or remove the trailing slash:

Using a redirect, the client will have to re-issue the request, enforcing a single acceptable URI for a resource.

If you need to serve multiple subdomains with the same wildcard certificate, the best way to handle them is with a Caddyfile like this, making use of the handle directive and host matchers:

Note that you must enable the ACME DNS challenge to have Caddy automatically manage wildcard certificates.

When a web page does its own routing, servers may receive lots of requests for pages that don't exist server-side, but which are renderable client-side as long as the singular index file is served instead. Web applications architected like this are known as SPAs, or single-page apps.

The main idea is to have the server "try files" to see if the requested file exists server-side, and if not, fall back to an index file where the client does the routing (usually with client-side JavaScript): try_files {path} /index.html

A typical SPA config usually looks something like this:

If your SPA is coupled with an API or other server-side-only endpoints, you will want to use handle blocks to treat them exclusively: